JBoss Community Archive (Read Only)

GateIn Portal 3.6

REST API

Overview

The portal provides a REST API to portal entities like Sites, Pages, and Navigation. All data is sent and received as JSON.

Base URL

There are two base URL's for the REST API. One that will be used if you need to authenticate and one that can be used to access resources anonymously.

Anonymous Base URL

http://<host>:<port>/rest/managed-components/api

Authenticated Base URL

http://<host>:<port>/rest/private/managed-components/api

Authentication

The REST API supports basic authentication. Below is an example of using basic auth in curl

curl -u <username> http://<host>:<port>/rest/private/managed-components/api

This allows users to access resources they have access to depending on the portal entity permissions.

Only members of the group /platform/administrators are allowed to add, update, or delete resources.

Content Type

Since all data is sent and received as JSON, appropriate HTTP headers need to be included in each HTTP request.

For clients receiving data the following HTTP header needs to be included in the request

Accept: application/json

For clients sending data the following HTTP header needs to be included in the request

Content-Type: application/json

Localization

Localization is supported for navigation nodes who have localized displayNames. To specify the language simply add the Accept-Language header to the HTTP request. For example for French you would have the following header

Accept-Language: fr

Resources

Below are the list of resources that are available in the REST API. All URL's below are relative to the base URL explained above.

Sites

List Sites

Sites are organized by site type, where site-type can be site, space, or dashboard.

GET /api/{site-type}s/

Note the 's' at the end of the URL. So space is /api/spaces/ and dashboard is /api/dashboards/

Parameter

Type

Default

Description

emptySites

boolean

false

Indicates to include empty sites (sites w/out pages or navigation)

offset

int

0

The offset of the results in a paginated request

limit

int

15

The maximum number of results to return in a paginated request

Below is an example that would list sites that have a siteType of 'site'.

Request
GET /api/sites
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "name" : "classic",
        "type" : "site",
        "url" : "/api/sites/classic"
    },
    {
        "name" : "mobile",
        "type" : "site",
        "url" : "/api/sites/mobile"
    }
]

Most responses include a url element which links to additional resources. The example above lists the sites that are available and their corresponding resource location. This should be used by clients instead of hard coding every location/url.

The url element is the full URL but for sake of brevity it's relative for the examples in this document.

Retrieve a site

To retrieve a site named site-name

GET /api/{site-type}s/{site-name}

Below is an example of retrieving the site classic.

Request
GET /api/sites/classic
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "classic",
    "type" : "site",
    "displayName" : "Classic",
    "description" : "GateIn default portal",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [
        {
            "key" : "showPortletInfo",
            "value" : "false"
        },
        {
            "key" : "sessionAlive",
            "value" : "onDemand"
        }
    ],
    "pages" : {"url" : "/api/sites/classic/pages"},
    "navigation" : {"url" : "/api/sites/classic/navigation"}
}

Create a site

To create a site named site-name

POST /api/{site-type}s/{site-name}

Below is an example of creating a site named 'foo'.

Request
POST /api/sites/foo
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "foo",
    "type" : "site",
    "displayName" : "Basic Portal",
    "description" : "This is basic portal template",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [{
        "key" : "sessionAlive",
        "value" : "onDemand"
    }],
    "pages" : {"url" : "/api/sites/foo/pages"},
    "navigation" : {"url" : "/api/sites/foo/navigation"}
}

Delete a site

To delete a site named site-name

DELETE /api/{site-type}s/{site-name}

Below is an example of deleting a site named 'foo'

Request
DELETE /api/sites/foo
Response
HTTP/1.1 200 OK
Content-Type: application/json

Update a site

To update a site named site-name

PUT /api/{site-type}s/{site-name}

Below is an example of updating the site 'classic' with a new description.

Request
PUT /api/sites/classic

Content-Type: application/json
{
   "description" : "Look ma, I updated the description !"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "classic",
    "type" : "site",
    "displayName" : "Classic",
    "description" : "Look ma, I updated the description !",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [
        {
            "key" : "showPortletInfo",
            "value" : "false"
        },
        {
            "key" : "sessionAlive",
            "value" : "onDemand"
        }
    ],
    "pages" : {"url" : "/api/sites/classic/pages"},
    "navigation" : {"url" : "/api/sites/classic/navigation"}
}

Pages

List Pages

GET /api/{site-type}s/{site-name}/pages

Parameter

Type

Default

Description

offset

int

0

The offset of the results in a paginated request

limit

int

15

The maximum number of results to return in a paginated request

Below is an example of listing all the pages for the site 'classic'.

Request
GET /api/sites/classic/pages
Response
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "name" : "homepage",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/homepage"
    },
    {
        "name" : "register",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/register"
    },
    {
        "name" : "sitemap",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/sitemap"
    }
]

Retrieve a page

To retrieve a page named page-name

GET /api/{site-type}s/{site-name}/pages/{page-name}

Below is an example of retrieving the page 'homepage'

Request
GET /api/sites/classic/pages/homepage
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "homepage",
    "displayName" : "Home Page",
    "description" : null,
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Create a page

To create a page named page-name

POST /api/{site-type}s/{site-name}/pages/{page-name}

Below is an example of creating a page 'newpage'

Request
POST /api/sites/classic/pages/newpage
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "newpage",
    "displayName" : "newpage",
    "description" : null,
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Delete a page

To delete a page named page-name

DELETE /api/{site-type}s/{site-name}/pages/{page-name}

Below is an example of deleting a page 'newpage'

Request
DELETE /api/sites/classic/pages/newpage
Response
HTTP/1.1 200 OK
Content-Type: application/json

Update a page

To update a page named page-name

PUT /api/{site-type}s/{site-name}/pages/{page-name}

Below is an example of updating the page 'homepage' with a new description

Request
PUT /api/sites/classic/pages/homepage

Content-Type: application/json
{
   "description" : "Look ma, I updated the description !"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "homepage",
    "displayName" : "Home Page",
    "description" : "Look ma, I updated the description !",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Navigation

Retrieve Navigation

GET /api/{site-type}s/{site-name}/navigation

Parameter

Type

Default

Description

scope

int

n/a

Specifies how many nodes to load (-1 for all)

Below is an example of retrieving the navigation for the site 'classic'

Request
GET /api/sites/classic/navigation
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "priority" : 1,
    "siteType" : "site",
    "siteName" : "classic",
    "nodes" : [
        {
            "name" : "home",
            "url" : "/api/sites/classic/navigation/home"
        },
        {
            "name" : "sitemap",
            "url" : "/api/sites/classic/navigation/sitemap"
        }
    ]
}

Below is an example of using the scope parameter to load more nodes which will include the actual node representation in the response

Request
GET /api/sites/classic/navigation?scope=1
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "priority" : 1,
    "siteType" : "site",
    "siteName" : "classic",
    "nodes" : [
        {
            "name" : "home",
            "uri" : "/portal/classic/home",
            "isVisible" : true,
            "visibility" : {"status" : "VISIBLE"},
            "iconName" : null,
            "displayName" : "Home",
            "displayNames" : [...]
            "children" : null,
            "page" : {
                "pageName" : "homepage",
                "siteName" : "classic",
                "siteType" : "site",
                "url" : "/api/sites/classic/pages/homepage"
            }
        },
        {
            "name" : "sitemap",
            "uri" : "/portal/classic/sitemap",
            "isVisible" : true,
            "visibility" : {"status" : "VISIBLE"},
            "iconName" : null,
            "displayName" : "SiteMap",
            "displayNames" : [...]
            "children" : null,
            "page" : {
                "pageName" : "sitemap",
                "siteName" : "classic",
                "siteType" : "site",
                "url" : "/api/sites/classic/pages/sitemap"
            }
        }
    ]
}

Retrieve a node

To retrieve a node with path node-path

GET /api/{site-type}s/{site-name}/navigation/{node-path}

parameter

type

default

description

scope

int

n/a

Specifies how many nodes to load (-1 for all)

Below is an example of retrieving the node 'home'

Request
GET /api/sites/classic/navigation/home
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

You can control the displayName value for localized nodes with the Accept-Language header. Below is an example of retrieving the node 'home' to display the displayName in French.

Request
GET /api/sites/classic/navigation/home
Accept-Language: fr
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Accueil",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Create a node

To create a node with path node-path

POST /api/{site-type}s/{site-name}/navigation/{node-path}

Below is an example of creating a new node 'newnode' under the home navigation node

Request
POST /api/sites/classic/navigation/home/newnode
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "newnode",
    "uri" : "/portal/classic/home/newnode",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "newnode",
    "children" : null,
    "page" : null
}

Delete a node

To delete a node with path node-path

DELETE /api/{site-type}s/{site-name}/navigation/{node-path}

Below is an example of deleting a node 'newnode'

Request
DELETE /api/sites/classic/navigation/home/newnode
Response
HTTP/1.1 200 OK
Content-Type: application/json

Update a node

To update a node with path node-path

PUT /api/{site-type}s/{site-name}/navigation/{node-path}

Below is an example of updating the node 'home' to point to the sitemap page rather then the homepage.

Request
PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
   "page" : {
        "pageName" : "sitemap",
        "siteName" : "classic",
        "siteType" : "site"
   }
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Test",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "sitemap",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/sitemap"
    }
}

Below is an example of updating the english localized displayName to 'Home Page'.

We have to include all the displayNames since the REST API will overwrite the values on the server with whatever we supply in the request.

Request
PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayNames" : [
        {
            "value" : "ホーム",
            "lang" : "ja"
        },
        {
            "value" : "Home Page",
            "lang" : "en"
        },
        {
            "value" : "首頁",
            "lang" : "zh-TW"
        },
        {
            "value" : "Domů",
            "lang" : "cs"
        },
        {
            "value" : "Accueil",
            "lang" : "fr"
        },
        {
            "value" : "主页",
            "lang" : "zh"
        },
        {
            "value" : "Главная",
            "lang" : "ru"
        },
        {
            "value" : "ترحيب",
            "lang" : "ar"
        },
        {
            "value" : "Trang chủ",
            "lang" : "vi"
        },
        {
            "value" : "Home",
            "lang" : "nl"
        },
        {
            "value" : "Inicio",
            "lang" : "es"
        },
        {
            "value" : "Principal",
            "lang" : "pt-BR"
        },
        {
            "value" : "Startseite",
            "lang" : "de"
        },
        {
            "value" : "홈",
            "lang" : "ko"
        },
        {
            "value" : "Home",
            "lang" : "it"
        },
        {
            "value" : "Додому",
            "lang" : "uk"
        },
        {
            "value" : "गृह पृष्‍ठ",
            "lang" : "ne"
        }
    ]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home Page",
    "displayNames" : [
        {
            "value" : "ホーム",
            "lang" : "ja"
        },
        {
            "value" : "Home Page",
            "lang" : "en"
        },
        {
            "value" : "首頁",
            "lang" : "zh-TW"
        },
        {
            "value" : "Domů",
            "lang" : "cs"
        },
        {
            "value" : "Accueil",
            "lang" : "fr"
        },
        {
            "value" : "主页",
            "lang" : "zh"
        },
        {
            "value" : "Главная",
            "lang" : "ru"
        },
        {
            "value" : "ترحيب",
            "lang" : "ar"
        },
        {
            "value" : "Trang chủ",
            "lang" : "vi"
        },
        {
            "value" : "Home",
            "lang" : "nl"
        },
        {
            "value" : "Inicio",
            "lang" : "es"
        },
        {
            "value" : "Principal",
            "lang" : "pt-BR"
        },
        {
            "value" : "Startseite",
            "lang" : "de"
        },
        {
            "value" : "홈",
            "lang" : "ko"
        },
        {
            "value" : "Home",
            "lang" : "it"
        },
        {
            "value" : "Додому",
            "lang" : "uk"
        },
        {
            "value" : "गृह पृष्‍ठ",
            "lang" : "ne"
        }
    ],
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Since the REST API overwrites the displayNames field we can delete existing displayNames by simply not including them. Below is an example of deleting all localized displayNames except for english.

Request
PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayNames" : [
        {
            "value" : "Home",
            "lang" : "en"
        }
    ]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [
        {
            "value" : "Home Page",
            "lang" : "en"
        }
    ],
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Below is an example of removing all localized displayNames from the home navigation node and replacing it with a non-localized (simple) displayName 'Home'.

Request
PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayName" : "Home"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [{"value" : "Home"}]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-10 12:55:39 UTC, last content change 2013-04-11 20:26:53 UTC.